@aws-sdk/credential-provider-imds

What is @aws-sdk/credential-provider-imds?

@aws-sdk/credential-provider-imds is a part of the AWS SDK for JavaScript. It provides a way to retrieve AWS credentials from the Instance Metadata Service (IMDS) on Amazon EC2 instances. This is particularly useful for applications running on EC2 instances that need to interact with other AWS services securely.

What are @aws-sdk/credential-provider-imds's main functionalities?

Retrieve Credentials from IMDS

This feature allows you to retrieve AWS credentials from the Instance Metadata Service (IMDS) on an EC2 instance. The code sample demonstrates how to use these credentials to make a call to the AWS STS service to get the caller identity.

const { fromInstanceMetadata } = require('@aws-sdk/credential-provider-imds');
const { STSClient, GetCallerIdentityCommand } = require('@aws-sdk/client-sts');

(async () => {
  const client = new STSClient({
    credentials: fromInstanceMetadata(),
  });
  const command = new GetCallerIdentityCommand({});
  const response = await client.send(command);
  console.log(response);
})();

Handle IMDS Timeout

This feature allows you to specify a timeout for the IMDS request. The code sample demonstrates how to set a 1-second timeout for retrieving credentials from IMDS and handle any potential errors.

const { fromInstanceMetadata } = require('@aws-sdk/credential-provider-imds');
const { STSClient, GetCallerIdentityCommand } = require('@aws-sdk/client-sts');

(async () => {
  const client = new STSClient({
    credentials: fromInstanceMetadata({ timeout: 1000 }), // 1 second timeout
  });
  const command = new GetCallerIdentityCommand({});
  try {
    const response = await client.send(command);
    console.log(response);
  } catch (error) {
    console.error('Error retrieving credentials:', error);
  }
})();

Other packages similar to @aws-sdk/credential-provider-imds

aws-sdk

The 'aws-sdk' package is the previous version of the AWS SDK for JavaScript. It also provides functionality to retrieve credentials from the Instance Metadata Service (IMDS) on EC2 instances. However, the new modular AWS SDK v3, which includes @aws-sdk/credential-provider-imds, offers better performance and smaller bundle sizes.

README

AWS Credential Provider for Node.JS - Instance and Container Metadata

This module provides two CredentialProvider factory functions, fromContainerMetadata and fromInstanceMetadata, that will create CredentialProvider functions that read from the ECS container metadata service and the EC2 instance metadata service, respectively.

A CredentialProvider function created with fromContainerMetadata will return a promise that will resolve with credentials for the IAM role associated with containers in an Amazon ECS task. Please see IAM Roles for Tasks for more information on using IAM roles with Amazon ECS.

A CredentialProvider function created with fromInstanceMetadata will return a promise that will resolve with credentials for the IAM role associated with an EC2 instance. Please see IAM Roles for Amazon EC2 for more information on using IAM roles with Amazon EC2.

Supported configuration

You may customize how credentials are resolved by providing an options hash to the fromContainerMetadata and fromInstanceMetadata factory functions. The following options are supported:

• timeout - The connection timeout (in milliseconds) to apply to any remote requests. If not specified, a default value of 1000 (one second) is used.
• maxRetries - The maximum number of times any HTTP connections should be retried. If not specified, a default value of 0 will be used.

Additionally, fromInstanceMetadata supports the following options:

• profile - The configuration profile to use. If not specified, the provider will use default profile name associated with the EC2 instance as reported by the Instance Metadata Service.